<!-- HTML header for doxygen 1.8.5-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.17"/>
<title>GenAVB/TSN: Socket API usage</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script src="http://www.freescale.com/files/abstract/misc/COLLATERALTEMPLATE_infocenter.js" type="text/javascript" xml:space="preserve"><!-- --></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="html_custom.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="nxp_logo.png"/></td>
  <td style="padding-left: 0.5em;">
   <div id="projectname">GenAVB/TSN
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.17 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('socket_usage.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="PageDoc"><div class="header">
  <div class="headertitle">
<div class="title">Socket API usage </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>The socket API allows the creation of a network endpoint and exchanging layer 2 network frames. Transmit and receive sockets are handled separately and each of them requires its own (unidirectional) socket. Parameters are set when the socket is opened and cannot be changed afterward.</p>
<h1><a class="anchor" id="sock_tx"></a>
Socket transmit</h1>
<p>Socket is created using <a class="el" href="group__socket.html#gac3d1a2a1cbc3198f48c011d98da2e696" title="Open tx socket.">genavb_socket_tx_open</a>.</p>
<p>Frames are transmitted using <a class="el" href="group__socket.html#gad80ab211fb3f2a0c807926368d41d63b" title="Socket transmit.">genavb_socket_tx</a> function. The function expects a continuous buffer including layer 2 header if <a class="el" href="group__socket.html#ggab5adeaf4eacc2cc7e7f649cf6456892ba8c100f50a99899d6b1ecc9dd76179ff7" title="Raw socket (only applies to transmit socket)">GENAVB_SOCKF_RAW</a> is set and excluding layer 2 header if not. The frame is copied before the function returns so that the provided buffer can be freed. A success return code means that the frame has been correctly queued.</p>
<p>Two transmit modes are available and are set using <a class="el" href="group__socket.html#gab5adeaf4eacc2cc7e7f649cf6456892b">genavb_sock_f_t</a> flag:</p><ul>
<li>If <a class="el" href="group__socket.html#ggab5adeaf4eacc2cc7e7f649cf6456892ba8c100f50a99899d6b1ecc9dd76179ff7" title="Raw socket (only applies to transmit socket)">GENAVB_SOCKF_RAW</a> is set, it's the caller responsability to set the layer 2 header. The l2 field of <a class="el" href="group__socket.html#structnet__address" title="Network address.">net_address</a> is not used.</li>
<li>If <a class="el" href="group__socket.html#ggab5adeaf4eacc2cc7e7f649cf6456892ba8c100f50a99899d6b1ecc9dd76179ff7" title="Raw socket (only applies to transmit socket)">GENAVB_SOCKF_RAW</a> isn't set, the layer 2 header is add internally based l2 field of <a class="el" href="group__socket.html#structnet__address" title="Network address.">net_address</a> and inserted automatically.</li>
</ul>
<p>Whatever the transmit mode, source MAC address and VLAN are overwritten by the stack. The socket networking parameters are set in <a class="el" href="group__socket.html#structgenavb__socket__tx__params">genavb_socket_tx_params</a> addr field. See <a class="el" href="socket_usage.html#net_addr">Network address</a> for a complete description. Only <a class="el" href="group__socket.html#gga54a99f7b450267929505a25dafd7e29fa037a73b1ddbdd1bb45d3271adb37537a" title="Layer 2.">PTYPE_L2</a> protocol type is supported in transmit.</p>
<p>The socket can be closed and its associated resources freed using <a class="el" href="group__socket.html#ga7397b58d8aa3c521d00513c02ecac215" title="Close tx socket.">genavb_socket_tx_close</a>.</p>
<h1><a class="anchor" id="sock_rx"></a>
Socket receive</h1>
<p>Socket is created using <a class="el" href="group__socket.html#ga993d76b4a4ce46cb8a9f8d4846b79440" title="Open rx socket.">genavb_socket_rx_open</a>.</p>
<p>Frames are received by calling <a class="el" href="group__socket.html#ga9a53948cb83c2f8836022cb158ffa64c" title="Socket receive.">genavb_socket_rx</a>, the buffer length must be at least the interface MTU size. The frames are copied to the provided buffer which needs to be continous.</p>
<p>Two receive modes are available and are set using <a class="el" href="group__socket.html#gab5adeaf4eacc2cc7e7f649cf6456892b">genavb_sock_f_t</a> flag:</p><ul>
<li>If <a class="el" href="group__socket.html#ggab5adeaf4eacc2cc7e7f649cf6456892ba9b5002d8fc384b98c87fa827be8bbbf5" title="Non-blocking mode (only applies to receive socket)">GENAVB_SOCKF_NONBLOCK</a> is set, the socket is configured in non-blocking mode and the call to <a class="el" href="group__socket.html#ga9a53948cb83c2f8836022cb158ffa64c" title="Socket receive.">genavb_socket_rx</a> will never block. If no frame is available for reading, the API returns <a class="el" href="group__generic.html#gga031a0b2111b623fef60d707141a995d5a343c7a1342f7baea1a0be56f9df9cd80" title="Socket no data available.">GENAVB_ERR_SOCKET_AGAIN</a>.</li>
<li>If <a class="el" href="group__socket.html#ggab5adeaf4eacc2cc7e7f649cf6456892ba9b5002d8fc384b98c87fa827be8bbbf5" title="Non-blocking mode (only applies to receive socket)">GENAVB_SOCKF_NONBLOCK</a> is not set, the socket is configured in blocking mode and the call to <a class="el" href="group__socket.html#ga9a53948cb83c2f8836022cb158ffa64c" title="Socket receive.">genavb_socket_rx</a> only returns if a frame has been received or because an error occured. To use the blocking mode a task needs to be dedicated to receive handling. (FreeRTOS only)</li>
</ul>
<p>The socket networking parameters are set in <a class="el" href="group__socket.html#structgenavb__socket__rx__params">genavb_socket_rx_params</a> addr field. See <a class="el" href="socket_usage.html#net_addr">Network address</a> for a complete description. The following receive protocol types are available:</p><ul>
<li><a class="el" href="group__socket.html#gga54a99f7b450267929505a25dafd7e29fa037a73b1ddbdd1bb45d3271adb37537a" title="Layer 2.">PTYPE_L2</a>: the frame matching is performed using the VLAN ID and the destination MAC address. The other fields of <a class="el" href="group__socket.html#structnet__address" title="Network address.">net_address</a> are not used.</li>
<li><a class="el" href="group__socket.html#gga54a99f7b450267929505a25dafd7e29fa617ea496cc731e1aa57b6b13b69dbd82" title="Non handled by genAVB stack.">PTYPE_OTHER</a>: the socket will receive all the frames which have not been received by another genAVB socket. This protocol type is generally used to connect a generic TCP/IP protocol stack.</li>
</ul>
<p>The socket can be closed and its associated resources freed using <a class="el" href="group__socket.html#ga0c98ea9974edededab7497f47f31c348" title="Close rx socket.">genavb_socket_rx_close</a>.</p>
<h1><a class="anchor" id="flow_control_sock"></a>
Flow control (non-blocking mode)</h1>
<p>In receive, two approaches are possible:</p><ul>
<li>the stream is periodic like isochronous time-sensitive traffic. The application is aware of the frames timing and therefore can just "poll" the socket at the expected time.</li>
<li>the stream has no known timing and the application needs to be notified when frames are available for read.</li>
</ul>
<p>In transmit, a time sensitive application expects being able to send its frames at a defined timing. If not it's generally a critical error and the send will be retried. Nonetheless, for some OS, some APIs may be available to be notified when buffer space is available for transmit.</p>
<p>Using the file descriptor returned by the <a class="el" href="group__socket.html#ga6e528bea165f730f74efe126b7f6036e" title="Retrieve the file descriptor associated with a given socket.">genavb_socket_rx_fd</a> and <a class="el" href="group__socket.html#ga6e528bea165f730f74efe126b7f6036e" title="Retrieve the file descriptor associated with a given socket.">genavb_socket_rx_fd</a> functions, an application may call poll/epoll/select system calls to sleep and be woken up only when received data is available or when buffer space is available for data to transmit.</p>
<h1><a class="anchor" id="net_addr"></a>
Network address</h1>
<p>The <a class="el" href="group__socket.html#structnet__address" title="Network address.">net_address</a> addr field is used to configure the socket networking parameters:</p><ul>
<li>ptype: the protocol type. Needs to be set to <a class="el" href="group__socket.html#gga54a99f7b450267929505a25dafd7e29fa037a73b1ddbdd1bb45d3271adb37537a" title="Layer 2.">PTYPE_L2</a> or <a class="el" href="group__socket.html#gga54a99f7b450267929505a25dafd7e29fa617ea496cc731e1aa57b6b13b69dbd82" title="Non handled by genAVB stack.">PTYPE_OTHER</a></li>
<li>port: the logical port number</li>
<li>vlan_id: the VLAN ID in network order (can be set to <a class="el" href="group__socket.html#ga74cbe20746c49877523d1e9f241d13cc" title="non standard value, used to indicate no vlan tag">VLAN_VID_NONE</a> if no vlan is required)</li>
<li>priority: traffic priority (range 0 to 7) (only used in transmit)</li>
<li>u.l2: the l2 address<ul>
<li>dst_mac: destination MAC address</li>
<li>protocol: the ether type (only used in transmit) </li>
</ul>
</li>
</ul>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- HTML footer for doxygen 1.8.5-->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul class="foot">
    <li class="footer"> &copy; 2017-2020 NXP
    </li>
  </ul>
</div>
</body>
</html>
